<!--$Id: intro.so,v 1.18 2006/11/13 18:05:03 bostic Exp $-->
<!--Copyright (c) 1997,2008 Oracle.  All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB Reference Guide: Introduction to the RPC client/server</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<a name="2"><!--meow--></a>
<table width="100%"><tr valign=top>
<td><b><dl><dt>Berkeley DB Reference Guide:<dd>RPC Client/Server</dl></b></td>
<td align=right><a href="../sequence/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rpc/client.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p align=center><b>Introduction to the RPC client/server</b></p>
<p>Berkeley DB includes an implementation of a client-server protocol using Sun
Microsystem's Remote Procedure Call Protocol.  RPC support is
available only for UNIX systems, and is not included in the Berkeley DB library by
default, but must be enabled during configuration.  See
<a href="../../ref/build_unix/conf.html">Configuring Berkeley DB</a> for more
information.  For more information on RPC itself, see your UNIX system
documentation or <i>RPC: Remote Procedure Call Protocol
Specification, RFC1831, Sun Microsystems, Inc., USC-ISI</i>.</p>
<p>Only some of the complete Berkeley DB functionality is available when using RPC.
The following functionality is available:</p>
<ol>
<li>The <a href="../../api_c/env_class.html">db_env_create</a> function and the <a href="../../api_c/env_class.html">DB_ENV</a> handle
methods.
<li>The <a href="../../api_c/db_class.html">db_create</a> function and the <a href="../../api_c/db_class.html">DB</a> handle methods.
<li>The <a href="../../api_c/txn_begin.html">DB_ENV-&gt;txn_begin</a>, <a href="../../api_c/txn_commit.html">DB_TXN-&gt;commit</a>, and <a href="../../api_c/txn_abort.html">DB_TXN-&gt;abort</a> methods.
</ol>
<p>The <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag to the <a href="../../api_c/env_open.html">DB_ENV-&gt;open</a> and <a href="../../api_c/db_open.html">DB-&gt;open</a> methods
may not be specified, that is, <a href="../../api_c/env_class.html">DB_ENV</a> and <a href="../../api_c/db_class.html">DB</a> handles  used
in RPC clients are not free-threaded.</p>
<p>The RPC client/server code does not support any of the user-defined
comparison or allocation functions; for example, an application using
the RPC support may not specify its own Btree comparison function.  If
your application requires only those portions of Berkeley DB, then using RPC
is fairly simple.  If your application requires other Berkeley DB
functionality, such as direct access to locking, logging or shared
memory buffer memory pools, then your application cannot use the RPC
support.</p>
<p>Although a client cannot specify a callback, Berkeley DB does support the
<a href="../../api_c/db_associate.html">DB-&gt;associate</a> call in a limited manner.  A client program
wanting to use a secondary index may do so only in a read-only fashion.
The primary and secondary databases must have been created locally on
the server machine.  Client programs must then open both the primary
and secondary databases with the <a href="../../api_c/db_open.html#DB_RDONLY">DB_RDONLY</a> flag set.  The client
must also specify a NULL callback for the <a href="../../api_c/db_associate.html">DB-&gt;associate</a> call.</p>
<p>The Berkeley DB RPC code requires that the client and server programs be
running the exact same version numbers.
The Berkeley DB RPC protocol version number is tied to the Berkeley DB major
and minor release numbers.
As such, the server program will reject requests from clients
using a different version number.</p>
<p><b>The Berkeley DB RPC support does not provide any security or authentication of
any kind.</b>  Sites needing any kind of data security measures must modify
the client and server code to provide whatever level of security they
require.</p>
<p>One particularly interesting use of the RPC support is for debugging Berkeley DB
applications.  The seamless nature of the interface means that with very
minor application code changes, an application can run outside of the
Berkeley DB address space, making it far easier to track down many types of
errors -- such as memory misuse.</p>
<p>Using the RPC mechanisms in Berkeley DB involves two basic steps:</p>
<ol>
<p><li>Modify your Berkeley DB application to act as a client and call the RPC
server.
<li>Run the <a href="../../utility/berkeley_db_svc.html">berkeley_db_svc</a> server program on the system where the
database resides.
</ol>
<table width="100%"><tr><td><br></td><td align=right><a href="../sequence/intro.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../rpc/client.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
</body>
</html>
